TCLSHELL

NAME

SYNOPSIS

DESCRIPTION

tcl [-q] [[-f] script]|[-c command] [args]

Tcl starts the interactive Tcl command interpreter. The Tcl shell provides an environment for writing, debugging and executing Tcl scripts. The functionality of the Tcl shell can also be obtained in any Tcl-based application.

The tcl command, issued without any arguments, invokes an interactive Tcl shell. If script is specified, then the script is executed noninteractively with args being supplied in the Tcl variable `argv'. If command is supplied, then this command (or series of commands, separated by `;') is executed, with `argv' containing args. The Tcl shell is intended as an environment for Tcl program development and execution. While it is not a full-featured interactive shell, it provides a comfortable environment for the interactive development of Tcl code. Note that the package library code described here overrides the unknown command provided as part of the standard Berkeley Tcl library facility, although Tcl source libraries coded to that standard can be loaded and used by Extended Tcl.  

INITIALIZATION SEQUENCE

The standard Tcl shell initialization consists of the following steps:

Search for a default file. The default file is a Tcl script that is executed to set important Tcl variables that govern startup, such as TCLPATH. The Tcl default file is searched for using the following algorithm: The current Extended Tcl version, represented by $ver, is included in the default file naming to allow multiple Tcl versions to exists on a system. Note that the Extended Tcl version is the standard Tcl version number with an alphabetic character added to indicated the version of Extended Tcl. The infox version command will return this version number.

- An environment variable, TCLDEFAULT, is checked for. If present, it is used as the name of the default file.

- A file, TCLDEFAULT, is looked for in the current directory.

- A global default file with is usually either /etc/default/tcl$ver or /usr/local/lib/tcldefault$ver. (Tcl may be compiled to use a different directory on some systems).

First, Tcl executes the default file. This file normally sets at least two Tcl variables: TCLPATH, which contains a list of directories that contain tcl source files, and TCLINIT, the full pathname of the Tcl source file that performs Tcl initialization. Other site-specific variables may also be set in this file.

Next, tcl executes the initialization file specified by the Tcl variable TCLINIT. This is normally the TclInit.Tcl file distributed with Tcl. This file defines the Tcl environment, including standard Tcl procs and variables.

FLAGS

-q

Quick initialization flag. If this flag is set the only initialization step performed is to locate the Tcl default file and save its name in the Tcl variable TCLDEFAULT. The file is not evaluated nor is the TclInit.tcl file. This provides for a faster start up, but does not make any of the standard Tcl procedures and facilities available.

-f

Take the next argument as a Tcl script to source rather than enter interactive mode. The -f flag is optional. Normally the first argument that does not start with a `-' is taken as the script to execute unless the `-c' option is specified. All following arguments are passed to the script in argv, thus any other Tcl shell flags must precede this option.

-c

Take the next argument as a Tcl command to execute. It may be series of commands to execute, separated by `;'. All following arguments are passed in argv, thus any other Tcl shell flags must precede this option.

--

Mark the end of the arguments to the Tcl shell. All arguments following this are passed in the Tcl variable argv. This is useful to pass arguments without attempting to execute a Tcl script.

TCLINIT FILE

The Tcl initialization file, normally TclInit.tcl in the main Tcl script directory, initializes the Tcl shell. It defines various Tcl procedures that are required to implement loading of Tcl source from libraries via the package libraries and autoload facilities.

If the Tcl is invoked interactively, it will source a .tclrc in the user's home directory, if it exists. Tcl is viewed primarly as a programming language, not an interactive shell, so the .tclrc is intended for use for loading development utilities, not to support programs, which should not rely on the user's environment.  

VARIABLES

The following variables are set and/or used by the Tcl shell.

argv

A list containing the arguments passed in from the command line, excluding arguments used by the Tcl shell. The first element is the first passed argument, not the program name.

interactiveSession

Set to 1 if Tcl shell is invoked interactively, or 0 if the Tcl shell is directly executing a script.

noAutoExec

If this variable exists and has a value of 1, then the Tcl shell will not attempt to exec an non-existent command as a shell command.

programName

The name that the Tcl shell is executing as. All directory components are removed from the program name.

scriptName

The name of the script that the Tcl shell is executing if the script was invoked on the command line.

TCLDEFAULT

Name of the default file that was used to locate all other files used by the Tcl shell.

TCLENV

Array that contains information used internally by various Tcl procedures that are part of the Tcl shell.

TCLENV(topLevelPromptHook)

Contains code to run to generate the prompt used when interactively prompting for commands. The code in this hook will be evaluated and the result will be used for the prompt.

TCLENV(downLevelPromptHook)

Contains code to run to generate the prompt used when interactively prompting for continuation of an incomplete command. The code in this hook will be evaluated and the result will be used for the prompt

TCLINIT

The name of the file that initializes, and does startup processing of, Tcl.

TCLPATH

Path to search to locate Tcl scripts. Used by the load and demand_load procedures.

HELP FACILITY

The help facility allows for display of help files extracted from the standard Tcl manual pages and Tcl scripts. Help files are structured in a multilevel directory tree of subjects and help files. The following commands and options are provided with the help package:

help

Help, without arguments, lists of all the top-level help subject directories and files.

help subjectdir

Displays all of help files and lower level subject files (if any exist) under the directory subjectdir.

help subjectdir/helpfile

Display the specified help file. The help output is passed through a simple pager if output exceeds 23 lines, pausing waiting for a return to be entered. If any other character is entered, the output is terminated.

helpcd [subjectdir]

Change the current subject directory, which is much like the Unix current directory. This directory can be changed with the helpcd command. If subjectdir is not specified, return to the top-level of the help tree. Help path names may also include ``..'' elements.

helppwd

Displays the current help subject directory.

help help | ?

Displays help on the help facility at any directory level.

apropos pattern

This command locates subjects by searching their one-line descriptions for a pattern. Apropos is useful when you can remember part of the name or description of a command, and want to search through the one-line summaries for matching lines. Full regular expressions may be specified (see the regexp command).

COMMAND RESULTS

The string result of a command typed at the Tcl shell command prompt is normally echoed back to the user. If an error occurs, then the string result is displayed, along with the error message. The error message will be preceded by the string ``Error:''.

The set command is a special case. If the command is called to set a variable (i.e. with two arguments), then the result will not be echoed. If only one argument, the name of a variable, is supplied to set, then the result will be echoed.  

EXECUTION OF UNIX COMMANDS

If an unknown Tcl command is entered from the command line, then the Unix command path, specified in the environment variable PATH, will be searched for a command of the same name. If found, the command will be executed. This feature is provided to enhance the interactive environment for developing Tcl scripts. This is only supported from the command line, not in script files or in procedures, to eliminate confusion. The exec or system command should be used to run Unix commands inside scripts.  

TCL SHELL PROCEDURES

The follow additional procedures are defined by the Tcl shell and may be generally useful:

load file Source a file, as with the source command, except search the TCLPATH for the file.

searchpath path file Search all directories in the specified path, which is a Tcl list, for the specified file. Returns the full path name of the file, or an empty string if the file is not found.

AUTOLOAD

autoload file proc1 [..procN]

The autoload procedure, defined in TclInit.tcl, allows the Tcl programmer to name one or more procedures and the file they are defined in. After autoload has been executed to inform Tcl of the presence of them, a subsequent attempt to execute one of the procedures will cause the corresponding file to be loaded transparently prior to executing the function. For example, executing:

autoload showproc.tcl showproc showprocs

tells Tcl to automatically load the file showproc.tcl the first time in the current session that either showproc or showprocs is executed.  

PACKAGE LIBRARIES

Package libraries work like autoload, except that a package library file can contain multiple independent Tcl packages. A package is a collection of related Tcl procedures.

The package library file is just a regular Unix text file, editable with your favorite text editor, containing packages of Tcl source code. The package library must end in .tlib, an index file with the suffix .tndx will be built corresponding to the package library. The start of a package is delimited by:

#@package: package_name proc1 [..procN]

These lines must start in column one. Everything between the package keyword and the next package keyword, or the end of the file, becomes part of the named package. The specified procedures, proc1..procN, are the entry points of the package. When a command named in a package command is executed and detected as an unknown command, all code in the specified package will be sourced. This package should define all of the procedures named on the package line, define any support procedures required by the package and do any package-specific initialization.

For example, in a package source file, the presence of the following line:

#@package: directory_stack pushd popd dirs

says that the text lines following that line in the package file up to the next package line or the end of the file is a package named directory_stack and that an attempt to execute either pushd, popd or dirs when the routine is not already defined will cause the directory_stack portion of the package file to be loaded.  

PACKAGE INDEX FILES

A package library file has associated with it an index file called a .tndx file. The .tndx file contains the names of the packages in the .tlib file, their addresses and lengths within the .tlib file and the functions that are to cause the different packages to be autoloaded when an attempt is made to execute them.

The first time Tcl tries to execute a procedure where the procedure doesn't exist and isn't an autoload, Tcl will search along TCLPATH looking for any files ending in .tlib. For each one it finds, it checks to see if there is a corresponding file in the same directory ending in .tndx. If the .tndx file doesn't exist, or if its date of last modification is older than that of the .tlib file, the .tndx is automatically (re)generated if possible. If Tcl can't regenerate the file (most likely due to file or directory permission problems), an error occurs.

Demand loading is also supported from indexes build by the mkindex.tcl program, supplied with standard Tcl. However, init.tcl is not loaded. Note that the info library command is not used to locate libraries by this shell; the TCLPATH variable is set by the default file and is used to locate the libraries.  

PACKAGE MANAGEMENT COMMANDS

Several commands are available for building and managing package libraries. If you are not building package libraries and are using the standard Tcl initialization file, they are all transparent. These commands are either defined or autoloaded by TclInit.tcl.

autoprocs Lists the names of all known autoload and package library procedures.

buildpackageindex libfile Build an index for a package library. The the libfile name must end with the suffix .tlib.

demand_load procname Attempt to load the specified procedure, either as an autoload function or by loading the package containing the procedure. If the package indexes have not been loaded for all package libraries in TCLPATH, they will be loaded. Out-of-date library indexes will be rebuilt if they are writable. The procedure returns 1 if the procedure was sucessfully loaded, or 0 if it was not.

loadlibindex libfile Load the package library index of the library file libfile (which must have the suffix .tlib). Package library indexes along the TCLPATH are loaded automatically on the first demand_load; this command is provided to explicitly load libraries that are not in the path. If the index file (with a .tndx suffix) does not exists or is out of date, it will be rebuilt if the user has directory permissions to create it.

packages Returns a list of the names of all known packages.

TCL SHELL INTERNAL STRUCTURE

This section discusses the internal structure of the standard Tcl initialization file and the facilities it implements. This is intended primarily for developers who want to customize these facilities for their applications.  

Autoload and Package Library Structures

The package library index consists of an entry for each package in the library, where each entry is a call to the TCLSH:defpkg procedure. Loading of the package index is done with the source command. The defpackage routine initializes elements of the TCLENV array which are used by demand_load to locate and load a package. The buildpackageindex procedure is contained in packages.tcl.

The following elements of the TCLENV are used to implement the autoload and package library facility.

TCLENV(PROC:procName)

Each procedure that is to be loaded by the demand_load command has an entry in this array, indexed by the concatenation of `PROC:' with the procedure name. If the entry is for a package, it is a list consisting `P' followed by the name of the package. The package name must be looked up in the TCLENV array to find the actual library file. If the entry is for an autoload procedure, it is a list consisting of 'F' followed by the name of the file to load.

TCLENV(PKG:packageName)

Each package has an entry in the array indexed by the concatenation of `PKG:' and the name of the package. The entry is a list containing the full path to the library file, the byte offset in the file of the start of the package, and the length of the package.

TCLENV(packageIndexesLoaded)

A boolean that indicates if the package indexes have been loaded. They will not be loaded until the first call to demand_load.

TCLENV(inUnknown)

Indicates if the unknown command is currently being executed. It is used to detect recursion in situations where an unknown command is found during unknown command processing.

The following procedures are used to implement the internals of the autoload and package library facility, and are defined by TclInit.tcl:

TCLSH:defpkg pkgname libfile offset len proc1 [..procN]

Define a package for the current interpreter. Pkgname is the name of the package to define, libfile is the full path to the library file. offset is the byte offset into the of the start of the package code; len is the length of the package code, in bytes, and proc1..procN are the entry point procedures defined by the package. This procedure is normally not called directly by the user or the user's script. The library index files consists of calls to this procedure to define every package in a library.

TCLSH:LoadOusterIndex dir

Load an index file, dir/tclIndex, of the type built by John Ousterhout's mkindex.tcl program (included with the standard Tcl distribution). This style of index defines procedure names and the files that contain them. It is a one-index-to-many-source-files structure. All of the files pointed to by this must reside in dir. The procedures in these libraries will be defined as if the autoload command had been used.

TCLSH:LoadPackageIndexes

This procedure searches the path defined by Tcl variable TCLPATH and loads all of the indexes for all of the .tlib package libraries in the path. If any of the indexes are older that their corresponding library file or do not exist, then they will be rebuilt if the user has write access to the directory. Also all Ousterhout-style indexes found along the path will be loaded.

unknown

This is the actual unknown command trap handler. It will first do a demand_load, loading the unknown command if it has been defined by autoload, or by a package library index. The library indexes will be be loaded if this is the first call to unknown. If the command is not found by demand_load, the Unix path (in the environment variable PATH, will be searched for the command. If it is found, it will be executed via the system command, providing full shell (sh) command line expansion, with output going to standard out rather than being returned as the result of the command. This binary path search will only occur if this is an interactive session running at the top level (i.e., not in a procedure or a script). This behavior can be disabled with the noAutoExec variable.

Index

NAME

SYNOPSIS

DESCRIPTION

INITIALIZATION SEQUENCE

FLAGS

TCLINIT FILE

VARIABLES

HELP FACILITY

COMMAND RESULTS

EXECUTION OF UNIX COMMANDS

TCL SHELL PROCEDURES

AUTOLOAD

PACKAGE LIBRARIES

PACKAGE INDEX FILES

PACKAGE MANAGEMENT COMMANDS

TCL SHELL INTERNAL STRUCTURE

Autoload and Package Library Structures